feat: Squad 2.0 decoupled backend and multi-host client adapters (Claude, Kiro, OpenCode, Cursor, Codex, Antigravity) - #2239

… repair

- Validate each record against its existing map key first in normalizeHandwrittenCastingRegistry so valid provenance records (e.g. agents.belanna named B'Elanna with .squad/agents/belanna/ avatar) preserve their map key
- Require valid retired_at on legacy retired records in isAcceptable so retired records missing retired_at reach normalization instead of early-exiting
- Resolve snapshot agent values first in normalizeHandwrittenHistory and reject unknown agent values or disagreement with a recognized ID key
- Require registry, history, and commit manifest generation metadata (transaction_id and revision) to agree before stripping and recommitting in recommitExistingPair
- Reject symlinked handwritten-archive-<sha256> directories and archive target files via assertNotSymlink before creating or writing archives

Refs #2239
Refs #2252

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c854ee92-c40c-4436-8a2c-901b1f781776

- Auto-select a single registered in-process harness in `squad_backend_send_message` when `harness` is omitted, and reject an omitted `harness` when multiple harnesses are registered instead of silently queueing; keep remote routing separate
- Default an omitted `limit` in `squad_backend_read_events` to `MAX_READ_EVENTS_LIMIT` (500)
- Read the response body outside the JSON parse `try/catch` in `DurableHttpSquadBackend.probe` so body timeouts and stream errors fail health checks
- Coordinate in-flight `adapter.submit` dispatches by `(conversationId, runId, seq)` and pass a deterministic `operationId` (`${conversationId}:${runId}:${seq}`) for crash-retry deduplication
- Remove queued approval deliveries for a turn when committing cancellation (`markCancelled` / terminal state) so `flushDeliveries` never retries or blocks on an obsolete approval
- Thread the publishing `harnessId` through `ensureSubscribed`, `applyEvent`, and `applyEventLocked` (including synchronous subscription replay) and verify it matches the turn's routed harness
- Reject a second distinct `approval-requested` event while a turn already has a `pendingApproval`
- Derive `createStateBackendStore` lock identity from the canonical shared storage (`.git` common dir across linked worktrees, resolved via `realpathSync.native`) and the state ref (`refs/heads/<branch>` or `refs/notes/<ref>`), unwrapping `TwoLayerBackend`
- Clear ambient `SQUAD_BACKEND_URL`, `SQUAD_BACKEND_TOKEN`, and `SQUAD_EXPERIMENTAL_BACKEND` before applying explicit test environment values in `McpStdioClient`

Refs #2239, #2253

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5ff02830-3b62-4a0a-8752-bc54a0bc3639

…ions (Layer 1)

Carves Layer 1 of #2239 targeting dev and applies all Layer 1 review fixes:
- Isolate host coordinator projections so non-Squad sessions are not hijacked:
  - Codex writes full coordinator prompt to .codex/agents/squad.md and only a short discovery pointer block in AGENTS.md
  - Kiro sets .kiro/steering/squad.md to inclusion: manual (loaded by .kiro/agents/squad.json)
  - Cursor sets .cursor/rules/squad.mdc to alwaysApply: false
- Make multi-client projection strictly opt-in (no default .claude/worktrees/ or NUL in .gitignore on plain init/upgrade)
- Synchronize coordinator.ts with .github/agents/squad.agent.md as the canonical coordinator source of truth
- Throw on unclosed or inverted Squad managed block markers in upsertBlock/removeBlock
- Normalize inline and dotted squad_state TOML definitions in upsertTomlTable/removeTomlTable without duplicates
- Import from @bradygaster/squad-sdk/client, merge repeated --client flags, preserve unknown portable client IDs in config.json with a warning, and reject symlinked .squad directories

Refs #2239

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a8a1fc8-bd63-4811-920c-7be89c631d5e

…m team.md (Layer 2)

Carves Layer 2 of #2239 targeting tamirdresher-microsoft-stack-1-client-adapters and applies all Layer 2 review fixes:
- Acquire the casting writer lock (with symlink/lstat guards) BEFORE reading registry.json, history.json, or registry-history.commit.json in repairHandwrittenCastingRegistry and backfillCastingRegistryFromTeam
- Do not leave *.handwritten.bak clutter in .squad/casting/ by default (only when options.keepBackup === true is explicitly passed)
- Restore the exact in-memory pre-repair snapshot to disk and rethrow if commitCastingRegistryPair fails (never fall back to writing a fresh cast or deleting registry-history.commit.json)
- Never touch or rewrite valid canonical registries or registries with existing cast history
- Validate handwritten registry repair in memory during `squad upgrade --dry-run` so dry-run previews succeed without mutating disk while still failing closed on corrupt/unrepairable registries
- Guard interactive prompts in `squad init` via `isInteractiveSession()`

Refs #2239

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c854ee92-c40c-4436-8a2c-901b1f781776

… repair

- Validate each record against its existing map key first in normalizeHandwrittenCastingRegistry so valid provenance records (e.g. agents.belanna named B'Elanna with .squad/agents/belanna/ avatar) preserve their map key
- Require valid retired_at on legacy retired records in isAcceptable so retired records missing retired_at reach normalization instead of early-exiting
- Resolve snapshot agent values first in normalizeHandwrittenHistory and reject unknown agent values or disagreement with a recognized ID key
- Require registry, history, and commit manifest generation metadata (transaction_id and revision) to agree before stripping and recommitting in recommitExistingPair
- Reject symlinked handwritten-archive-<sha256> directories and archive target files via assertNotSymlink before creating or writing archives

Refs #2239
Refs #2252

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c854ee92-c40c-4436-8a2c-901b1f781776

…tract (Layer 3)

Carves Layer 3 of #2239 targeting tamirdresher-microsoft-stack-2-casting-repair and applies all Layer 3 review fixes:
- Export the experimental conversation & harness contract from `@bradygaster/squad-sdk/backend` only (`BACKEND_CONTRACT_STAGE = 'experimental'`) without re-exporting from the root `@bradygaster/squad-sdk` barrel
- Gate `squad_backend_*` MCP tools in `squad state-mcp` behind explicit opt-in (`--experimental-backend`, `SQUAD_EXPERIMENTAL_BACKEND=1`, or `SQUAD_BACKEND_URL`)
- Fix `createFileStateStore` lock contention `catch` block so persistent `EACCES`/`EPERM` errors respect `lockTimeoutMs` and sleep between polls instead of spinning forever, and reject symlinked `.squad` or store root directories via `lstatSync`
- Track pending harness submissions in `LocalSquadBackend.sendMessage` so a failed or interrupted `harness.submit` is recovered on a same-`(runId, seq)` retry and returns the original admission cursor
- Implement real cross-process `wx` file locking with stale-lock recovery and symlink guards in `createStateBackendStore`
- Add per-attempt `requestTimeoutMs` (default 15_000 ms) via `AbortSignal.timeout` in `DurableHttpSquadBackend`

Refs #2239

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5ff02830-3b62-4a0a-8752-bc54a0bc3639

- Auto-select a single registered in-process harness in `squad_backend_send_message` when `harness` is omitted, and reject an omitted `harness` when multiple harnesses are registered instead of silently queueing; keep remote routing separate
- Default an omitted `limit` in `squad_backend_read_events` to `MAX_READ_EVENTS_LIMIT` (500)
- Read the response body outside the JSON parse `try/catch` in `DurableHttpSquadBackend.probe` so body timeouts and stream errors fail health checks
- Coordinate in-flight `adapter.submit` dispatches by `(conversationId, runId, seq)` and pass a deterministic `operationId` (`${conversationId}:${runId}:${seq}`) for crash-retry deduplication
- Remove queued approval deliveries for a turn when committing cancellation (`markCancelled` / terminal state) so `flushDeliveries` never retries or blocks on an obsolete approval
- Thread the publishing `harnessId` through `ensureSubscribed`, `applyEvent`, and `applyEventLocked` (including synchronous subscription replay) and verify it matches the turn's routed harness
- Reject a second distinct `approval-requested` event while a turn already has a `pendingApproval`
- Derive `createStateBackendStore` lock identity from the canonical shared storage (`.git` common dir across linked worktrees, resolved via `realpathSync.native`) and the state ref (`refs/heads/<branch>` or `refs/notes/<ref>`), unwrapping `TwoLayerBackend`
- Clear ambient `SQUAD_BACKEND_URL`, `SQUAD_BACKEND_TOKEN`, and `SQUAD_EXPERIMENTAL_BACKEND` before applying explicit test environment values in `McpStdioClient`

Refs #2239, #2253

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5ff02830-3b62-4a0a-8752-bc54a0bc3639

…osts (Layer 4)

Split from #2239 (Layer 4 of 4):
- Canonicalize @bradygaster/squad-sdk/client across architecture, overview, quickstart, and SDK docs
- Add Experimental Preview / Bring Your Own Server callouts for @bradygaster/squad-sdk/backend and document opt-in --experimental-backend / SQUAD_EXPERIMENTAL_BACKEND=1 MCP tools
- Update all 5-host lists to all 7 hosts (copilot, claude, kiro, opencode, cursor, codex, antigravity) and align generated-file tables with Layer 1 projections
- Consolidate architecture and multi-client docs into published Astro pages and align v0.2 specs

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 3ed7a60c-f40f-40e8-8b56-c39cf1a0ffe9

… Cursor, Codex, and Antigravity [1/4] (#2251)

* feat(client): add multi-host --client adapters and opt-in CLI projections (Layer 1)

Carves Layer 1 of #2239 targeting dev and applies all Layer 1 review fixes:
- Isolate host coordinator projections so non-Squad sessions are not hijacked:
  - Codex writes full coordinator prompt to .codex/agents/squad.md and only a short discovery pointer block in AGENTS.md
  - Kiro sets .kiro/steering/squad.md to inclusion: manual (loaded by .kiro/agents/squad.json)
  - Cursor sets .cursor/rules/squad.mdc to alwaysApply: false
- Make multi-client projection strictly opt-in (no default .claude/worktrees/ or NUL in .gitignore on plain init/upgrade)
- Synchronize coordinator.ts with .github/agents/squad.agent.md as the canonical coordinator source of truth
- Throw on unclosed or inverted Squad managed block markers in upsertBlock/removeBlock
- Normalize inline and dotted squad_state TOML definitions in upsertTomlTable/removeTomlTable without duplicates
- Import from @bradygaster/squad-sdk/client, merge repeated --client flags, preserve unknown portable client IDs in config.json with a warning, and reject symlinked .squad directories

Refs #2239

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a8a1fc8-bd63-4811-920c-7be89c631d5e

* fix(client): audit fixes for --client adapters (Codex TOML agent, symlink root handling, EOL/indent-preserving merges)

- H1: Codex coordinator is now a TOML custom agent (.codex/agents/squad.toml with name/description/developer_instructions, escaped multi-line string); AGENTS.md pointer, ANCHORS, dispatch text and uninstall updated
- H2: resolveInsideRoot realpaths the root once and only lstats components below it, so junctioned/symlinked ancestors (OneDrive, ~/code -> /Volumes) work; syncClients returns early with no requested/configured clients before any filesystem checks
- M2: symlinked target files inside the root (AGENTS.md -> CLAUDE.md) are written through; symlinks escaping the root are still refused
- M1: new 'lines' projection kind for .gitignore (plain lines under a `# squad:<id>` comment, no HTML markers); uninstall removes only the lines Squad added
- M3: emitted content follows the existing file's dominant EOL (LF for new files) for blocks, lines, JSON, TOML and removals
- M4: JSON merges preserve indentation (tabs/N spaces) and trailing-newline; OpenCode targets opencode.jsonc when it is the only config and reports an error instead of clobbering JSONC with comments
- M5: only persist newly requested clients whose projection had no errors (configured ones stay); atomic temp+rename writes; `squad upgrade --dry-run --client` prints the clients it would project (syncClients dryRun option)
- M6: real-CLI tests gated behind SQUAD_REAL_CLI_TESTS=1, PATH-only binary discovery, no hardcoded paths, shell:false, cursor-agent check is read-only
- changeset wording updated; tests added/updated in test/clients.test.ts

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

* fix(client): resolve all 6 Copilot PR review threads on #2251

- apply.ts (Thread 1): preserve parsed TOML key segments across sectionHeader,
  tableHeaderKeys, findTable, stripConflictingDottedAndInline, and removeTomlTable
  so quoted-dot server names ([mcp_servers."squad_state.env"]) remain untouched
- apply.ts (Thread 2): track multiline basic (""") and literal (''') string
  boundaries in assignmentEnd and advance scanners across multiline assignments
  so embedded TOML examples in developer_instructions are never rewritten
- apply.ts (Thread 3): refuse to extend enclosing ancestor inline/scalar tables
  (e.g. mcp_servers = { other = ... }) or non-table squad_state assignments
- portable.ts (Thread 4): trim before sensitivity checks and redact bare
  credential prefixes (ghp_, github_pat_, sk-, glpat-, xox*, AKIA, JWT) so
  they never surface in unknown-ID warnings or persist in config.json
- adapters.ts & clients-real-cli.test.ts (Thread 5): project native Codex
  .codex/agents/squad.toml role and verify real-CLI role discovery + coordinator
  developer_instructions activation on spawn_agent
- clients.ts & clients.test.ts (Thread 6): document the default Copilot
  bootstrap exception (.github/agents/squad.agent.md + .mcp.json) and test
  both plain runInit and runUpgrade command pipelines directly

Refs #2251

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a8a1fc8-bd63-4811-920c-7be89c631d5e

---------

Co-authored-by: Copilot <Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7a8a1fc8-bd63-4811-920c-7be89c631d5e
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

…ry-run support [2/4] (#2252)

* feat(casting): repair handwritten casting registries and backfill from team.md (Layer 2)

Carves Layer 2 of #2239 targeting tamirdresher-microsoft-stack-1-client-adapters and applies all Layer 2 review fixes:
- Acquire the casting writer lock (with symlink/lstat guards) BEFORE reading registry.json, history.json, or registry-history.commit.json in repairHandwrittenCastingRegistry and backfillCastingRegistryFromTeam
- Do not leave *.handwritten.bak clutter in .squad/casting/ by default (only when options.keepBackup === true is explicitly passed)
- Restore the exact in-memory pre-repair snapshot to disk and rethrow if commitCastingRegistryPair fails (never fall back to writing a fresh cast or deleting registry-history.commit.json)
- Never touch or rewrite valid canonical registries or registries with existing cast history
- Validate handwritten registry repair in memory during `squad upgrade --dry-run` so dry-run previews succeed without mutating disk while still failing closed on corrupt/unrepairable registries
- Guard interactive prompts in `squad init` via `isInteractiveSession()`

Refs #2239

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c854ee92-c40c-4436-8a2c-901b1f781776

* fix(casting): per-record handwritten registry repair, charter-derived backfill ids, roll-forward-safe rollback

- H3: normalize handwritten registries per record — records that already parse as valid provenance records are preserved verbatim (all fields, timestamps, per-record universe); only incomplete records get missing fields synthesized. Preserve and bump the registry revision instead of resetting it. Archive pre-repair originals under handwritten-archive-<sha256>/ by default (keepBackup: false opts out) and report backupPath.
- H4: backfillCastingRegistryFromTeam derives agent ids from the team.md Charter column (.squad/agents/<id>/charter.md) or a charter whose ## Identity name matches; rows with no provable folder fail the backfill closed with a dropped list. Fix the test that expected "b-elanna" for the belanna folder.
- M8: wrapper-less shapes only accept record values carrying name/persistent_name/display_name/role; bare-string values and non-agent metadata are reported instead of guessed. Non-Latin names, duplicate names and id collisions no longer drop silently — RepairResult.dropped is populated and the repair fails closed; squad upgrade prints the reason and each dropped entry.
- M7: commitPairWithRollback only restores the pre-repair snapshot when the commit failed before its journal became durable (never on CastingCommitInDoubtError or after a successful commit), restores via temp+fsync+rename, and attaches restore failures as cause. recoverCastingRegistryTransaction runs under the lock before the snapshot so pending journals roll forward first.
- M9: single exported hasExistingCastHistory (empty arrays/objects are not history) replaces the CLI copy; a history.json holding one Init Mode snapshot consistent with the handwritten registry is normalized instead of blocking the repair. squad upgrade --dry-run previews the team.md backfill.
- Low: strip UTF-8 BOM before JSON.parse; anchor the team.md universe regex to a line start / table cell and fail the backfill closed instead of inventing one; recommit of a manifest-mismatched pair bumps the revision and requires a readable history object.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

* fix(casting): address PR #2252 review threads on handwritten registry repair

- Validate each record against its existing map key first in normalizeHandwrittenCastingRegistry so valid provenance records (e.g. agents.belanna named B'Elanna with .squad/agents/belanna/ avatar) preserve their map key
- Require valid retired_at on legacy retired records in isAcceptable so retired records missing retired_at reach normalization instead of early-exiting
- Resolve snapshot agent values first in normalizeHandwrittenHistory and reject unknown agent values or disagreement with a recognized ID key
- Require registry, history, and commit manifest generation metadata (transaction_id and revision) to agree before stripping and recommitting in recommitExistingPair
- Reject symlinked handwritten-archive-<sha256> directories and archive target files via assertNotSymlink before creating or writing archives

Refs #2239
Refs #2252

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c854ee92-c40c-4436-8a2c-901b1f781776

---------

Co-authored-by: Copilot <Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c854ee92-c40c-4436-8a2c-901b1f781776
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

…tract [3/4] (#2253)

* feat(backend): add experimental /backend conversation and harness contract (Layer 3)

Carves Layer 3 of #2239 targeting tamirdresher-microsoft-stack-2-casting-repair and applies all Layer 3 review fixes:
- Export the experimental conversation & harness contract from `@bradygaster/squad-sdk/backend` only (`BACKEND_CONTRACT_STAGE = 'experimental'`) without re-exporting from the root `@bradygaster/squad-sdk` barrel
- Gate `squad_backend_*` MCP tools in `squad state-mcp` behind explicit opt-in (`--experimental-backend`, `SQUAD_EXPERIMENTAL_BACKEND=1`, or `SQUAD_BACKEND_URL`)
- Fix `createFileStateStore` lock contention `catch` block so persistent `EACCES`/`EPERM` errors respect `lockTimeoutMs` and sleep between polls instead of spinning forever, and reject symlinked `.squad` or store root directories via `lstatSync`
- Track pending harness submissions in `LocalSquadBackend.sendMessage` so a failed or interrupted `harness.submit` is recovered on a same-`(runId, seq)` retry and returns the original admission cursor
- Implement real cross-process `wx` file locking with stale-lock recovery and symlink guards in `createStateBackendStore`
- Add per-attempt `requestTimeoutMs` (default 15_000 ms) via `AbortSignal.timeout` in `DurableHttpSquadBackend`

Refs #2239

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5ff02830-3b62-4a0a-8752-bc54a0bc3639

* fix(backend): align experimental backend docs with implementation; harden durable-http, locks and MCP opt-in

- H5: rewrite test/squad-20-security-contracts.test.ts to exercise product code
  (createFileStateStore/resolveInsideRoot guards, mergeMcpServer/installClients,
  LocalSquadBackend idempotency/epochs/approvals/cursors, backend-mcp, DurableHttp);
  delete self-referential reference guards; proposal no longer claims an
  "executable contract" or CI-blocking gates
- H6: proposal, ADR and spec now describe the shipped behavior: opaque
  harness-supplied approval hash echoed back, cooperative client-asserted
  epochs (explicitly not a security boundary), unsigned cursors; stronger
  properties moved to "Future work / not implemented"
- H7: replace spec TypeScript contracts with the real signatures from
  backend/types.ts (SquadBackend, HarnessAdapter, RunState, ...); golden-trace
  fixture uses real BackendEnvelope.type names and the e2e runner no longer
  needs a translation table
- M10: squad_backend_send_message returns BackendError 'unavailable' when no
  harness is registered instead of queueing forever; health/negotiate expose
  harnesses: [] and executionAvailable: false; tool descriptions and specs
  state the bridge is transcript/event-log only
- M11: git-ignore .squad/backend/ in the upgrade scaffold (no merge=union)
- M12: SQUAD_BACKEND_URL alone no longer enables the tools; DurableHttp
  validates baseUrl (https, or http to loopback), uses redirect: 'error'
- M13: health probes get AbortSignal.timeout; file-store lock acquisition is
  async (lockAsync) for backend methods; read() only treats ENOENT as missing;
  corrupt conversation JSON surfaces as BackendError with the path; temp file
  is fsync'd before rename; spec documents whole-file snapshot limitation
- M14: createStateBackendStore requires a deterministic lock root (no mkdtemp
  fallback) and no longer prunes lock directories after release
- Low: MCP arg validation (role/parts/protocols/limit cap 500), generic
  message for non-contract errors, Windows reserved device names rejected as
  conversation ids, misplaced comment fixed, real-binary tests gated behind
  SQUAD_REAL_CLI_TESTS=1, flaky opt-in test timeout raised

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

* fix(stack): align e2e scenarios with audited adapter/casting behavior; keep configured state backend out of .squad/backend; fail-closed casting repair reports instead of crashing

- e2e expectation updates for the audited stack behavior: Codex agent is
  `.codex/agents/squad.toml`; `.gitignore` projections are `# squad:claude`
  plain lines (exact restoration on removal still asserted);
  `normalizeHandwrittenCastingRegistry` callers use the new
  `NormalizeHandwrittenResult` shape; repair archives originals under
  `handwritten-archive-<sha256>/` instead of `.handwritten.bak`; a
  manifest-only recommit bumps the revision by one and keeps agents/history;
  team.md backfill resolves ids from charter folders (`belanna`, not
  `b-elanna`) and `parseTeamRoster` members carry `charterId`; a roster with
  no provable agent folder fails closed with the dropped row named
- role-keyed fixture now uses object entries (`tester: { name }`) since bare
  strings are rejected by design; a dedicated case asserts the bare-string
  rejection reason
- createStateBackendStore: a configured non-local state backend (git-notes,
  orphan, or any backend without a `root`) no longer gets its lock root from
  the team `.squad` dir. Locks live in a deterministic machine-local
  directory derived from the backend identity (`cwd` or the new `lockAnchor`
  option); `createMcpBackend` passes `lockAnchor` instead of `squadDir`, so
  `.squad/backend/` is never created when a non-local backend is configured
- squad upgrade: when the handwritten-registry repair fails closed and the
  pair is not readable as a managed pair, `ensureCastingDefaults` and the
  pre-preflight repair in `runUpgrade` throw an actionable error (reason,
  dropped entries, how to fix) instead of the generic "exactly one
  authoritative file exists" / preflight error

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

* docs(spec): align Codex anchor and Claude .gitignore lines with projection code

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

* fix(upgrade): keep legacy casting preflight authoritative; enrich only its generic error with the handwritten-repair reason

The fail-closed handwritten-registry path pre-empted preflightCastingRegistryPair, so legacy`entries` registries (and --dry-run) got the new error instead of the legacy migration/refusal they had before.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

* fix(backend): resolve all 9 PR #2253 Copilot review findings

- Auto-select a single registered in-process harness in `squad_backend_send_message` when `harness` is omitted, and reject an omitted `harness` when multiple harnesses are registered instead of silently queueing; keep remote routing separate
- Default an omitted `limit` in `squad_backend_read_events` to `MAX_READ_EVENTS_LIMIT` (500)
- Read the response body outside the JSON parse `try/catch` in `DurableHttpSquadBackend.probe` so body timeouts and stream errors fail health checks
- Coordinate in-flight `adapter.submit` dispatches by `(conversationId, runId, seq)` and pass a deterministic `operationId` (`${conversationId}:${runId}:${seq}`) for crash-retry deduplication
- Remove queued approval deliveries for a turn when committing cancellation (`markCancelled` / terminal state) so `flushDeliveries` never retries or blocks on an obsolete approval
- Thread the publishing `harnessId` through `ensureSubscribed`, `applyEvent`, and `applyEventLocked` (including synchronous subscription replay) and verify it matches the turn's routed harness
- Reject a second distinct `approval-requested` event while a turn already has a `pendingApproval`
- Derive `createStateBackendStore` lock identity from the canonical shared storage (`.git` common dir across linked worktrees, resolved via `realpathSync.native`) and the state ref (`refs/heads/<branch>` or `refs/notes/<ref>`), unwrapping `TwoLayerBackend`
- Clear ambient `SQUAD_BACKEND_URL`, `SQUAD_BACKEND_TOKEN`, and `SQUAD_EXPERIMENTAL_BACKEND` before applying explicit test environment values in `McpStdioClient`

Refs #2239, #2253

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5ff02830-3b62-4a0a-8752-bc54a0bc3639

---------

Co-authored-by: Copilot <Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5ff02830-3b62-4a0a-8752-bc54a0bc3639
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

…umentation [4/4] (#2254)

* docs(squad-2.0): consolidate multi-client and backend docs across 7 hosts (Layer 4)

Split from #2239 (Layer 4 of 4):
- Canonicalize @bradygaster/squad-sdk/client across architecture, overview, quickstart, and SDK docs
- Add Experimental Preview / Bring Your Own Server callouts for @bradygaster/squad-sdk/backend and document opt-in --experimental-backend / SQUAD_EXPERIMENTAL_BACKEND=1 MCP tools
- Update all 5-host lists to all 7 hosts (copilot, claude, kiro, opencode, cursor, codex, antigravity) and align generated-file tables with Layer 1 projections
- Consolidate architecture and multi-client docs into published Astro pages and align v0.2 specs

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 3ed7a60c-f40f-40e8-8b56-c39cf1a0ffe9

* docs(squad-2.0): reflect audited behavior (Codex TOML agent, .gitignore lines, backend opt-in and harness caveats, https-only durable-http)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841

* docs(squad-2.0): address #2254 review threads, prepare 2.0.0 release notes & pack smoke test

- Clarify in reference/sdk.md, reference/config.md, and reference/cli.md that createSquadBackend / DurableHttpSquadBackend require explicit baseUrl (and optional token), while automatic SQUAD_BACKEND_URL / SQUAD_BACKEND_TOKEN lookup applies only to squad state-mcp when experimental backend tools are enabled
- Use canonical BACKEND_CAPABILITIES tokens (cursor-reconnect, approvals, cancel-run, typed-content-parts) in durable-backend-and-custom-harness.md
- Give each turn a distinct approvalId and track (runId, seq) per conversation and approvalId in DemoHarnessAdapter
- Update .changeset/squad-2-0-multi-host-clients.md with major bumps for @bradygaster/squad, @bradygaster/squad-sdk, and @bradygaster/squad-cli and release-notes summary
- Add v2.0.0 release notes to whatsnew.md, Upgrading to Squad 2.0 section to scenarios/upgrading.md and get-started/migration.md, and host capability matrix / Phase 2 limitations to architecture and multi-client docs
- Add test/squad-20-pack-smoke.test.ts for npm pack clean-install and v1.1.0 -> 2.0 upgrade/rollback verification

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 3ed7a60c-f40f-40e8-8b56-c39cf1a0ffe9

---------

Co-authored-by: Copilot <Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 3ed7a60c-f40f-40e8-8b56-c39cf1a0ffe9
Copilot-Session: 92888fd8-c715-4d1d-a60f-893a7a157841